home *** CD-ROM | disk | FTP | other *** search
/ Aminet 31 / Aminet 31 (1999)(Schatztruhe)[!][Jun 1999].iso / Aminet / util / libs / IdmLib.lha / IdmLib / AutoDoc / ProgrammingIdm.doc < prev   
Encoding:
Text File  |  1999-02-28  |  5.2 KB  |  148 lines
  1.  
  2. ---------------------------------------------------------------------
  3. An introduction to using Idm.library in you applications.
  4. ---------------------------------------------------------------------
  5.  
  6. Idm.library is a standard Amiga run-time library that enables the
  7. programmer to quickly identify files. Idm.library may be used with any
  8. programming language that can handle calls to Amiga run time libraries.
  9.  
  10. To correctly identify files the following step of events must occur:
  11.  
  12. 1. Open the library using exec.library/OpenLibrary()
  13.  
  14. 2. Call the Idm.library/IdmAllocIdInfo() function with the desired tags.
  15.    This function (if successful) will return a pointer to an IdInfo
  16.    structure. This pointer *MUST* later be released with the function
  17.    Idm.library/IdmFreeIdInfo().
  18.  
  19. 3. Call the Idm.library/IdmObtainIOLen() function. This function MUST
  20.    be called if you don't want to load the whole file to memory, but
  21.    instead want to load the smallest amount of bytes possible. Loading
  22.    the smallest amount of bytes is normally the prefered method when
  23.    scanning many files (eg: whole directories).
  24.  
  25. 4. Load the file to memory (remember to allocate some memory before
  26.    doing this :) - If you require the whole file to be in memory then
  27.    simply load it, but if you don't need the whole file in memory, then
  28.    load the amount specified by Idm.library/IdmObtainIOLen() off the
  29.    *START* of the file. Remember to Seek() to the start of the file.
  30.  
  31. 5. Identify the file. By passing the IdInfo structure you got earlier
  32.    from Idm.library/IdmAllocIdInfo() + a pointer to the file + the
  33.    amount of bytes that have been loaded off the file + a taglist
  34.    to the Idm.library/IdmIdentifyMem() function, you will get a string
  35.    pointer or NULL. If you get a NULL then this means that Idm.library
  36.    was unable to identify the file, else if you get a non-NULL then
  37.    this will point to a descriptive NULL-terminated identification string.
  38.  
  39.    You can also examine the IdInfo structure to get more information
  40.    on errors, etc.
  41.  
  42. 6. Do your stuff. Report the filetype to the user of your program, etc.
  43.  
  44. 7. Free your file, again this is up to you.
  45.  
  46. 8. Free the IdInfo structure that you got from the Idm.library/
  47.    IdmAllocIdInfo() function.
  48.  
  49. 9. Close Idm.library.
  50.  
  51. These are the minimum steps required to identify a file. You might
  52. also want to obtain more information on the currently installed version
  53. of Idm.library. To do this Idm.library provides the following support
  54. functions fow this purpose:
  55.  
  56. IdmObtainLibInfo() - Get some general information on Idm.library.
  57. IdmFreeLibInfo()   - Free the structure returned by IdmObtainLibInfo().
  58.  
  59. The function IdmObtainLibInfo() will return pointer to the following
  60. structure (example in C) else NULL on a failure:
  61.  
  62. struct IdmLibInfo
  63. {
  64.     ULONG   IdmLI_MagicId;
  65.     UWORD   IdmLI_Version;
  66.     UWORD   IdmLI_Revision;
  67.     ULONG   IdmLI_AmtKnown;
  68.     struct  IdmKnownList *IdmLI_IDList;
  69.     ULONG   IdmLI_IOLen;
  70.     UWORD   IdmLI_Reserved01;
  71.     UWORD   IdmLI_Reserved02;
  72.     APTR    IdmLI_MaxName;
  73.     UBYTE  *IdmLI_DateStr;
  74.     ULONG   IdmLI_AmtCat;
  75. };
  76.  
  77. Remember to pass this structure to IdmFreeLibInfo() when you are
  78. finished with it. Here is what each field means:
  79.  
  80. IdmLI_Version
  81. IdmLI_Revision
  82.  
  83.  The version and revision of the currently installed version of Idm.library.
  84.  
  85. IdmLI_AmtKnown
  86.  
  87.  The amount of file types known to this version of Idm.library.
  88.  
  89. IdmLI_IDList
  90.  
  91.  A pointer to a stand Amiga linked list header. This list will contain
  92.  all the filetype names known to current version Idm.library. Each node
  93.  in this list will be extended with the following structure.
  94.  
  95.  struct IdmKnownNode
  96.  {
  97.      struct  Node IdmKN_NodeHead;
  98.      UWORD   IdmKN_Pad01;
  99.      ULONG   IdmKN_Magic;
  100.      UWORD   IdmKN_Flags;
  101.      UWORD   IdmKN_Catagory;
  102.      UWORD   IdmKN_InternId;
  103.      UWORD   IdmKN_Pad02;
  104.      ULONG   IdmKN_IOLen;
  105.  };
  106.  
  107.  All of the fields in this node are private. Work is still in progress
  108.  on this structure. Accessing these fields might break your program.
  109.  
  110.  However, you may access the ln_Name (LN_NAME in assembly) field in the
  111.  node at the start of the structure. This will contain the name of
  112.  current idetification string.
  113.  
  114.  This list is designed for attaching to a gadtools.library listview
  115.  gadget or similar.
  116.  
  117. IdmLI_IOLen
  118.  
  119.  The minimun IOLen required by this version of Idm.library. This value is the
  120.  same as the result returned by the Idm.library/IdmObtainIOLen() function.
  121.  
  122. IdmLI_MaxName
  123.  
  124.  Identification string of filetype that requires the most amount of bytes to
  125.  be loaded off the start of a file to ensure a proper identification check.
  126.  
  127.  In other words, just ignore it, Its is normally used for debugging, etc.
  128.  
  129. IdmLI_DateStr
  130.  
  131.  A pointer to a date string. This date indicates the compile date of
  132.  the current version of Idm.library. It looks like DD-MMM-YY.
  133.  
  134. IdmLI_MagicId
  135. IdmLI_Reserved01
  136. IdmLI_Reserved02
  137.  
  138.  Ignore these, they are used internally. Accessing these will break
  139.  your program! You have been warned.
  140.  
  141. IdmLI_AmtCat
  142.  
  143.  Don't access this, its a work-in-progress thing for a future version of
  144.  Idm.library. Accessing this might break your program. 
  145.  
  146. ---------------------------------------------------------------------
  147. This file is copyright © 1999 Andrew Bell, created on Mon/22/Feb/1999
  148.